<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Spirit FAQ</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Spirit 2.59">
<link rel="up" href="../index.html" title="Spirit 2.59">
<link rel="prev" href="support/utree.html" title="The utree data structure">
<link rel="next" href="notes.html" title="Notes">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="support/utree.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="notes.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="spirit.faq"></a><a class="link" href="faq.html" title="Spirit FAQ">Spirit FAQ</a>
</h2></div></div></div>
<h4>
<a name="spirit.faq.h0"></a>
      <span class="phrase"><a name="spirit.faq.i_m_getting_multiple_symbol_definition_errors_while_using_visual_c____anything_i_could_do_about_that_"></a></span><a class="link" href="faq.html#spirit.faq.i_m_getting_multiple_symbol_definition_errors_while_using_visual_c____anything_i_could_do_about_that_">I'm
      getting multiple symbol definition errors while using Visual C++. Anything
      I could do about that?</a>
    </h4>
<p>
      Do you see strange multiple symbol definition linker errors mentioning <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">failed</span></code>
      and <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">qi</span><span class="special">::</span><span class="identifier">rule</span></code>?
      Then this FAQ entry might be for you.
    </p>
<p>
      <a href="http://www.boost.org/libs/mpl/index.html" target="_top">Boost.Mpl</a> implements
      a macro <code class="computeroutput"><span class="identifier">BOOST_MPL_ASSERT_MSG</span><span class="special">()</span></code> which essentially is a more powerful version
      of static_assert. Unfortunately under certain circumstances using this macro
      may lead to the aforementioned linker errors.
    </p>
<p>
      <a href="http://boost-spirit.com" target="_top">Spirit</a> allows you to define a
      preprocessor constant disabling the usage of <code class="computeroutput"><span class="identifier">BOOST_MPL_ASSERT_MSG</span><span class="special">()</span></code>, while switching to <code class="computeroutput"><span class="identifier">BOOST_STATIC_ASSERT</span><span class="special">()</span></code> instead. For that you need define BOOST_SPIRIT_DONT_USE_MPL_ASSERT_MSG=1.
      Do this by adding
    </p>
<pre class="programlisting"><span class="special">-</span><span class="identifier">DBOOST_SPIRIT_DONT_USE_MPL_ASSERT_MSG</span><span class="special">=</span><span class="number">1</span>
</pre>
<p>
      on the compiler command line or by inserting a
    </p>
<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_SPIRIT_DONT_USE_MPL_ASSERT_MSG</span> <span class="number">1</span>
</pre>
<p>
      into your code before any Spirit headers get included.
    </p>
<p>
      Using this trick has no adverse effects on any of the functionality of <a href="http://boost-spirit.com" target="_top">Spirit</a>. The only change you might see
      while using this workaround is less verbose error messages generated from static_assert.
    </p>
<h4>
<a name="spirit.faq.h1"></a>
      <span class="phrase"><a name="spirit.faq.i_m_very_confused_about_the_header_hell_in_my_boost_spirit_directory__what_s_all_this_about_"></a></span><a class="link" href="faq.html#spirit.faq.i_m_very_confused_about_the_header_hell_in_my_boost_spirit_directory__what_s_all_this_about_">I'm
      very confused about the header hell in my boost/spirit directory. What's all
      this about?</a>
    </h4>
<p>
      The boost/spirit directory currently holds two versions of the Spirit library:
      <a href="../../../../../libs/spirit/classic/index.html" target="_top"><span class="emphasis"><em>Spirit.Classic</em></span></a>
      (former V1.8.x) and SpiritV2. Both are completely independent and usually not
      used at the same time. Do not mix these two in the same grammar.
    </p>
<p>
      <a href="../../../../../libs/spirit/classic/index.html" target="_top"><span class="emphasis"><em>Spirit.Classic</em></span></a>
      evolved over years in a fairly complex directory structure:
    </p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">actor</span>
<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">attribute</span>
<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">core</span>
<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">debug</span>
<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">dynamic</span>
<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">error_handling</span>
<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">iterator</span>
<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">meta</span>
<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">symbols</span>
<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">tree</span>
<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">utility</span>
</pre>
<p>
      While introducing Spirit V2 we restructured the directory structure in order
      to accommodate two versions at the same time. All of <a href="../../../../../libs/spirit/classic/index.html" target="_top"><span class="emphasis"><em>Spirit.Classic</em></span></a>
      now lives in the directory
    </p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">classic</span>
</pre>
<p>
      where the directories above contain forwarding headers to the new location
      allowing to maintain application compatibility. The forwarding headers issue
      a warning (starting with Boost V1.38) telling the user to change their include
      paths. Please expect the above directories/forwarding headers to go away soon.
    </p>
<p>
      This explains the need for the directory
    </p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span>
</pre>
<p>
      which contains forwarding headers as well. But this time the headers won't
      go away. We encourage application writers to use only the includes contained
      in this directory. This allows us to restructure the directories underneath
      if needed without worrying application compatibility. Please use those files
      in your application only. If it turns out that some forwarding file is missing,
      please report this as a bug.
    </p>
<p>
      Spirit V2 is not about parsing only anymore (as <a href="../../../../../libs/spirit/classic/index.html" target="_top"><span class="emphasis"><em>Spirit.Classic</em></span></a>).
      It now consists out of 3 parts (sub-libraries): <span class="emphasis"><em>Spirit.Qi</em></span>,
      <span class="emphasis"><em>Spirit.Karma</em></span>, and <span class="emphasis"><em>Spirit.Lex</em></span>. The
      header files for those live in
    </p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">qi</span>
<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">karma</span>
<span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">lex</span>
</pre>
<p>
      and have forwarding headers in
    </p>
<pre class="programlisting"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span>
</pre>
<p>
      <span class="emphasis"><em>Spirit.Qi</em></span> is the direct successor to <a href="../../../../../libs/spirit/classic/index.html" target="_top"><span class="emphasis"><em>Spirit.Classic</em></span></a>
      as it implements a DSEL (domain specific embedded language) allowing to write
      parsers using the syntax of C++ itself (parsers in the sense turning a sequence
      of bytes into an internal data structure). It is not compatible with <a href="../../../../../libs/spirit/classic/index.html" target="_top"><span class="emphasis"><em>Spirit.Classic</em></span></a>,
      the main concepts are similar, though.
    </p>
<p>
      <span class="emphasis"><em>Spirit.Karma</em></span> is the counterpart to <span class="emphasis"><em>Spirit.Qi</em></span>.
      It implements a similar DSEL but for writing generators (i.e. the things turning
      internal data structures into a sequence of bytes, most of the time - strings).
      <span class="emphasis"><em>Spirit.Karma</em></span> is the Yang to <span class="emphasis"><em>Spirit.Qi</em></span>'s
      Yin, it's almost like a mirrored picture.
    </p>
<p>
      <span class="emphasis"><em>Spirit.Lex</em></span> is (as the name implies) a library allowing
      to write lexical analyzers. These are either usable stand alone or can be used
      as a front end for <span class="emphasis"><em>Spirit.Qi</em></span> parsers. If you know flex
      you shouldn't have problems understanding <span class="emphasis"><em>Spirit.Lex</em></span>.
      This library actually doesn't implement the lexer itself. All it does is to
      provide an interface to pre-existing lexical analyzers. Currently it's using
      Ben Hansons excellent <a href="http://www.benhanson.net/lexertl.html" target="_top">Lexertl</a>
      library (proposed for a Boost review, BTW) as its underlying workhorse.
    </p>
<p>
      Again, don't use any of the header files underneath the boost/spirit/home directory
      directly, always include files from the boost/spirit/include directory.
    </p>
<h4>
<a name="spirit.faq.h2"></a>
      <span class="phrase"><a name="spirit.faq.why_doesn_t_my_symbol_table_work_in_a__code__phrase_role__identifier__no_case__phrase___code__directive_"></a></span><a class="link" href="faq.html#spirit.faq.why_doesn_t_my_symbol_table_work_in_a__code__phrase_role__identifier__no_case__phrase___code__directive_">Why
      doesn't my symbol table work in a <code class="computeroutput"><span class="identifier">no_case</span></code>
      directive?</a>
    </h4>
<p>
      In order to perform case-insensitive parsing (using <a class="link" href="qi/reference/directive/no_case.html" title="Parser Directive Inhibiting Case Sensitivity (no_case[])"><code class="computeroutput"><span class="identifier">no_case</span></code></a>) with a symbol table (i.e.
      use a <a class="link" href="qi/reference/string/symbols.html" title="Symbols Parser (symbols)"><code class="computeroutput"><span class="identifier">symbols</span><span class="special">&lt;&gt;</span></code></a> parser in a <code class="computeroutput"><span class="identifier">no_case</span></code>
      directive), that symbol table needs to be filled with all-lowercase contents.
      Entries containing one or more uppercase characters will not match any input.
    </p>
<h4>
<a name="spirit.faq.h3"></a>
      <span class="phrase"><a name="spirit.faq.i_m_getting_a_compilation_error_mentioning__code__phrase_role__identifier__boost__phrase__phrase_role__special______phrase__phrase_role__identifier__function__phrase___code__and_or___________code__phrase_role__identifier__boost__phrase__phrase_role__special______phrase__phrase_role__identifier__function4__phrase___code___what_does_this_mean_"></a></span><a class="link" href="faq.html#spirit.faq.i_m_getting_a_compilation_error_mentioning__code__phrase_role__identifier__boost__phrase__phrase_role__special______phrase__phrase_role__identifier__function__phrase___code__and_or___________code__phrase_role__identifier__boost__phrase__phrase_role__special______phrase__phrase_role__identifier__function4__phrase___code___what_does_this_mean_">I'm
      getting a compilation error mentioning <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">function</span></code>
      and/or <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">function4</span></code>. What does this mean?</a>
    </h4>
<p>
      If you are using Visual C++ and have an error like:
    </p>
<pre class="programlisting">error C2664: 'bool boost::function4&lt;R,T0,T1,T2,T3&gt;::operator ()(T0,T1,T2,T3) const' :
    cannot convert parameter 4 from '...' to '...'
</pre>
<p>
      or you are using GCC and have an error like:
    </p>
<pre class="programlisting">error: no match for call to '(const boost::function&lt;bool ()(...)&gt;) (...)'
note: candidates are: ... boost::function4&lt;R,T1,T2,T3,T4&gt;::operator()(T0,T1,T2,T3) const [with ...]
</pre>
<p>
      then this FAQ entry may help you.
    </p>
<p>
      The definition of a Rule or Grammar may contain a skip parser type. If it does,
      it means that non-terminal can only be used with a skip parser of a compatible
      type. The error above arises when this is not the case, i.e.:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
          a non-terminal defined with a skip parser type is used without a skip parser;
          for example, a rule with a skip parser type is used inside a <code class="computeroutput"><span class="identifier">lexeme</span></code> directive, or a grammar with a
          skip parser type is used in <code class="computeroutput"><span class="identifier">parse</span></code>
          instead of <code class="computeroutput"><span class="identifier">phrase_parse</span></code>,
        </li>
<li class="listitem">
          or a non-terminal is used with a skip parser of an incompatible type; for
          example, a rule defined with one skip parser type calls a second rule defined
          with another, incompatible skip parser type.
        </li>
</ul></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
        The same applies to <span class="emphasis"><em>Spirit.Karma</em></span>, replacing 'skip parser'
        and <code class="computeroutput"><span class="identifier">lexeme</span></code> by 'delimit generator'
        and <code class="computeroutput"><span class="identifier">verbatim</span></code>. Similarly,
        corresponding error messages in <span class="emphasis"><em>Spirit.Karma</em></span> reference
        <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">function3</span></code> and the 3rd parameter (instead
        of the 4th).
      </p></td></tr>
</table></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="support/utree.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="notes.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
